Read Me Palm OS SDK 4.0

IMPORTANT:  Read Before Using the Accompanying Software

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =
P a l m   O S   S o f t w a r e   D e v e l o p m e n t   K i t
= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

***************************************************************
* IMPORTANT INFORMATION REGARDING FUTURE OS COMPATIBILITY     *
***************************************************************

In preparation for future Palm OS versions, Palm engineering is recommending
that developers DO NOT directly access internal data structures. Palm is
creating "Glue" routines, which are found in PalmOSGlue, to access these
structures. To test your code to see if it might break on a future version of
Palm OS, you should do the following:

-  In the file BuildDefaults.h (which is located within the "Incs" folder inside
   the "Palm OS Support" folder), locate the following line (it is near the end
   of the file):

     #ifndef DO_NOT_ALLOW_ACCESS_TO_INTERNALS_OF_STRUCTS

-  To test your applications compatibility you should define this as follows:

     #define DO_NOT_ALLOW_ACCESS_TO_INTERNALS_OF_STRUCTS
     #ifndef DO_NOT_ALLOW_ACCESS_TO_INTERNALS_OF_STRUCTS

-  Compile your application as you normally do, and fix the potential
   incompatibilities that are identified.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ IMPORTANT INFORMATION REGARDING METROWERKS CODEWARRIOR      +
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

- Palm OS SDK 4.0 and CodeWarrior for Palm OS R7

  All of the examples and other Metrowerks project (.mcp) files were last saved
  using the CodeWarrior Pro 5 IDE (version 4.0.4 build 486). This version is
  the predecessor to the IDE which ships with CodeWarrior for Palm OS R7.

  When opening these project files you will be prompted to convert these files
  to the new IDE. This will cause no problem and should be done when using the
  new version of the IDE.

- MSL Runtime Palm OS Libraries and CodeWarrior for Palm OS R7

  If it is necessary to rebuild the MSL Runtime Palm OS Libraries (in the
  project MSL Runtime Palm OS.mcp) and you are using CodeWarrior for Palm OS R7,
  you will need to go to the Metrowerks web site and download the latest MSL
  code. This should only be necessary if you wish to rebuild these libraries.
  The libraries that ship with the Palm OS 4.0 SDK will still work. There have
  been some bug fixes since the release of these files by Metrowerks.

- Checking for updates for Metrowerks components

  From time to time Metrowerks updates some of the components such as the IDE
  and other plug-ins. To make sure that your Metrowerks components are up to
  date please check for updates and patches on the Metrowerks web site:
  http://www.metrowerks.com/download/

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ ENHANCEMENTS AND FIXES -- WHAT'S NEW                        +
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

- Palm OS Support Folder Name

  You will notice that the "Palm OS Support" folder no longer contains the
  version number. This change will make upgrades easier and less confusing. To
  determine the specific version of a file, you should use "Get Info" on a
  Macintosh system and "Properties" on Windows. Also, all of the headers now
  include the following line in their header blocks:

    * Release: Palm OS SDK 4.0 (00000)

  The number inside the parentheses refers to an internal Palm build number.
  Check this number to make sure that you have the latest version of the file.

- Examples

  All samples that ship with the Palm OS 4.0 SDK have been updated to use the
  "Palm OS Support" folder.

  In addition, the Finger and Puzzle examples are GCC compatible.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ KNOWN ISSUES                                                +
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

+-------------------------------------------------------------+
+ Constructor for Palm OS                                     +
+-------------------------------------------------------------+

Using Constructor on a Japanese version of Microsoft Windows:

  Issue: Due to a library limitation, Constructor for Windows cannot process
  resource files with pathnames containing certain multi-byte characters, such
  as some Japanese Kanji characters. Saving or opening resource files from
  any directories where the path contains Japanese characters is likely to
  fail. This includes saving resource files to the desktop.

  Resolution: When running Constructor on a Japanese version of Windows, you
  should save your Constructor resource files in folders with single-byte ASCII
  (that is, English) names.

PRC Editing and Menus:

  When editing PRC menu (MBAR) resources, do not change menu item IDs or
  the Palm application may no longer function correctly. When editing a PRC
  file, Constructor ensures that menu item IDs are not changed accidentally by
  encoding them into the menu item names that appear in the menu editor.

  For example, say you have a standard Edit menu with an "Undo" item. In
  Constructor's menu editor, this menu item will appear as "Undo (ID=10000)".
  You may edit the menu item text, but do not disturb the '(ID=nnn)'
  suffix or the menu item ID may be altered when you save the PRC file.

  When editing PRC files, after you save the changes the project will "visually"
  close and reopen. This is due to the fact that the new PRC file is being
  revalidated. As this is happening, there is a progress indicator telling you
  that the file is being revalidated. This process happens very quickly; on most
  computers, it will be unnoticeable.

+-------------------------------------------------------------+
+ General                                                     +
+-------------------------------------------------------------+

WinGlueDrawChar and WinGlueDrawTruncChars fail with the 3.1.1 update on Latin
devices (they just draw the default square character). This update was shipped
on the IBM Workpad, and was available for download on Palm's website.

TxtGlueStripSpaces(Char *, Boolean, Boolean) does not do anything if it is
passed a string containing only spaces.

The HostControl.h file that ships with the Palm OS 4.0 SDK is different from
the HostControl.h file that ships with Palm OS Emulator. If you need to use
Palm OS Emulator-specific HostControl functionality, then you should use the
version of HostControl.h that comes with Palm OS Emulator.

While using Palm Debugger attached to Palm OS Emulator, if you enter the
command  ft "foo"  in the Palm Debugger, you will get an error message about
missing parameters. If you then press enter, Palm OS Emulator will crash.

While using Simulator, the importall and exportall commands don't work with
absolute directory paths.  This is because a colon (":") gets prepended to
the directory path.

For example:

  importall -u 0 "Macintosh HD:PalmDev:Simulator:Import"
  exportall 0 "Macintosh HD:PalmDev:Simulator:Export"

becomes

  ":Macintosh HD:PalmDev:Simulator:Import"
  ":Macintosh HD:PalmDev:Simulator:Export"

Simulator console commands (Free, Lock, Unlock, Info, Resize, and Setowner)
will cause a bus error if used with <LocalID> and -card 1.

On debug ROMs, the error "Window.c, Line:126, Bad window" will be given to any
application that tries to draw a bitmap whose bitdepth is greater than the
device officially supports.  Version 2.0 WCAs that have high depth bitmaps will
receive this error in Clipper.  Because Palm OS knows how to down-render
bitmaps, the bitmaps still draw correctly.  As a result, you may ignore this
error.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ INSTALLATION INSTRUCTIONS                                   +
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

+-------------------------------------------------------------+
+ Manual Installation                                         +
+-------------------------------------------------------------+

Macintosh

1.  Locate the "CodeWarrior Support" folder which is in the "SDK" folder.

2.  Move the contents of the "(Project Stationery)" folder--the "Palm OS
    Application" folder--into the "(Project Stationery)" folder where
    CodeWarrior is installed on your local drive.

3.  Move the items located inside the "Codewarrior plugins" folder in the
    "SDK" folder into their respective folders where CodeWarrior is installed
    on your local drive. This will include the following:

    - Move "PalmRez Post Linker" from the "Linkers" folder on the SDK to the
      "Linkers" folder inside the "CodeWarrior Plugins" folder where your
      CodeWarrior is installed on your local drive. This will replace the old
      "PalmRez Post Linker" file.

    - Move "PalmRez Panel" from the "Preference Panels" folder on the SDK to
      the "Preference Panels" folder inside the "CodeWarrior Plugins" folder
      where CodeWarrior is installed on your local drive.  This will replace
      the old "PalmRez Panel" file.

      Note: If you are doing development on a Japanese system, then replace the
      "PalmRez Panel" file with "PalmRez-J Panel" file. You can have only one
      PalmRez Preference Panel on your system at a time.

    - Move the "Support" folder from the SDK to the "Codewarrior Plugins"
      folder on your local system. If a "Support" folder already exists, then
      copy only the "PalmRez Japanese Support" file to your existing "Support"
      folder.

    - Copy the "Palm OS Support" folder from the SDK into the directory
      where CodeWarrior is installed on your local drive.

    - Manually copy any other files located on the SDK or downloaded from
      the web to your local drive.

Windows - CodeWarrior

1.  Locate the "CodeWarrior Support" folder which is in the "SDK" folder.

2.  Move the contents of the "(Project Stationery)" folder--the "Palm OS
    Application" folder--into the "Stationery" folder where CodeWarrior is
    installed on your local drive.

3.  Move the items located inside the "Codewarrior plugins" folder on the SDK
    into their respective folders where CodeWarrior is installed on your local
    drive. This will include the following:

    - Move the "PalmRezPostLinker.dll" from the "Linkers" folder on the SDK to
      the "Linkers" folder inside the "Bin\Plugins" folder where CodeWarrior is
      installed on your local drive. This will replace the old
      "PalmRezPostLinker.dll" file.

    - Move the "PPalmRez.dll" from the "Preference Panels" folder on the SDK to
      the "Preference Panels" folder inside "Bin\Plugins" folder where
      CodeWarrior is installed on your local drive. This will replace the old
      "PPalmRez.dll" file.

      Note: If you are doing development on a Japanese system replace the
      "PPalmRez.dll" with "PPalmRez-J.dll". You can have only one PalmRez
      Preference Panel in your system at a time.

    - Move the "Support" folder from the SDK to the "Bin\Plugins" folder on
      your local system. If a "Support" folder already exists, copy only the
      "PalmRez Japanese Support" file to your existing "Support" folder.

    - Copy the "Palm OS Support" folder from the SDK into the root of your
      CodeWarrior installation on your local drive.

    - Manually copy any other files located on the SDK or downloaded from the
      web to your local drive.


GCC / PRC-Tools on Windows or Unix

You need to extract the contents of sdk40-core into a directory tree
alongside your other SDKs, and with a similar directory structure.
For prc-tools 2.0 and later, the details are as follows:

1.  Locate your PalmDev directory, which is:
    - On Unix:  "/opt/palmdev" with prc-tools 2.1 or later, otherwise
      "/usr/local/palmdev".
    - On Windows:  "C:\PalmDev" by default -- you may have chosen another
      location when you installed prc-tools.

2.  Extract the contents of the sdk40-core archive in your PalmDev directory.

3.  Rename the top level directories so that prc-tools will recognize them:
    - Rename the "Palm OS Support" directory to "sdk-4".
    - Within this new "sdk-4" directory, rename "Incs" to "include".
    - Within this new "sdk-4" directory, rename "GCC Libraries" to "lib".

4.  The resulting directory structure should look like this:

	.../palmdev/sdk-4
	.../palmdev/sdk-4/include
	.../palmdev/sdk-4/include/Core etc
	.../palmdev/sdk-4/lib
	.../palmdev/sdk-4/lib/m68k-palmos-coff

5.  With prc-tools 2.1, at this point you can build with this SDK by
    using the "-palmos4" option.

6.  You can set this SDK to be used by default by creating an "sdk"
    symlink pointing to "sdk-4":

      [within the .../palmdev directory]
      rm -f sdk; ln -s sdk-4 sdk

    PRC-Tools 2.0 does not understand the "-palmos4" option.  As a result,
    with that version you can only use this SDK via the default "sdk" symlink.

    (It is possible to add the "-palmos4" option to prc-tools 2.0, but it is
    less effort just to upgrade to 2.1.  Details of adding the option to 2.0
    can be found in the palm-dev-forum archives.)

Earlier versions of prc-tools based on GCC 2.7.2.2, such as prc-tools 0.5.0,
cannot support everything in this SDK.  You may wish to upgrade, or, if you
continue to use an old prc-tools with this SDK, the installation is similar but
more involved.  You should locate your existing header files, and copy the
contents of "Palm OS Support/Incs" to a "PalmOS4" directory, but collapsing any
subdirectories which don't appear in your existing PalmOS[1-3] directories.

If you have problems using this SDK with prc-tools 2.0 or earlier, you should
upgrade to prc-tools 2.1, which is more robust when searching for SDKs.

+-------------------------------------------------------------+
+ Installation using Installers                               +
+-------------------------------------------------------------+

Macintosh (Installer)

This installer will only install the components needed by CodeWarrior to your
local drive. For all other items you can drag the folder to the
necessary place.

1.  Start the "Palm OS(R) SDK 4.0 Installer" application.

2.  Locate the drive of the CodeWarrior installation that you wish to update.

3.  Select the installation choice from the drop down menu located at the top
    of the installer.

4.  The following items will be installed by this installer:

    - The "Palm OS Application" project stationary folder will be added to your
      "(Project Stationery)" folder.
    - "PalmPlugin" will be added to your
      "Metrowerks CodeWarrior:CodeWarrior Plugins:Debuggers" folder.
    - "PalmRez Post Linker" will be added to your
      "Metrowerks CodeWarrior:CodeWarrior Plugins:Linkers" folder.
    - "PalmRez Panel" will be added to your
      "Metrowerks CodeWarrior:CodeWarrior Plugins:Preference Panels" folder.
    - "PalmRez Japanese Support" will be added to your
      "Metrowerks CodeWarrior:CodeWarrior Plugins:Support" folder.
    - "Constructor for Palm OS" will be added to your "Palm OS Constructor"
      folder and remove the old version.
    - "Palm OS Support" folder will be added to your "Metrowerks CodeWarrior"
      folder.
    - On English systems, Japanese Support will be installed to your
      "Palm OS Extras:Japanese" folder.
    - "Palm OS SDK Licenses" will be installed to root of your CodeWarrior
      installation.

Windows

This installer will only install the components needed by CodeWarrior to your
local drive. For all other items you can drag the folder to the necessary place.

1.  Start the "PalmOS 4.0 SDK.exe" application. This will unarchive and start
    the installer.

2.  Follow the instructions displayed by the installer.

3.  Locate the CodeWarrior installation that you wish to have updated, and
    install the SDK in the corresponding location.

4.  The following items will be installed by this installer:

    For CodeWarrior installations:

    - "Palm OS Application" project stationary folder will be added to your
      "Project Stationery" folder.
    - "PalmPlugin.dll" will be added to your "bin\plugins\Debugger" folder.
    - "PalmRezPostLinker.dll" will be added to your "bin\plugins\Linker" folder.
    - "PPalmRez.dll" will be added to your "bin\plugins\Preference Panel"
      folder.
    - "PalmRez Japanese Support" will be added to your "bin\plugins\Support"
      folder.
    - "Constructor for Palm OS.exe", "CONSTRUCTOR FOR PALM OS.HLP", and
      "cgrtoc.cnt" will be added to your "bin" folder.
    - "Palm OS Support" folder will be added to the root of your CodeWarrior
      installation.
    - "PPalmRez-J.dll" will be installed to your "Palm OS Extras\Japanese
      Support" folder.
    - "Palm OS SDK Licenses" folder will be created in the root of your
      CodeWarrior installation.
    - "Readme.txt" will be installed to the root of your CodeWarrior
      installation.

    For GCC Installations:

    - "sdk-4" will be created at the root of your "PalmDev" installation.
    - "Palm OS SDK Licenses" folder will be created at the root of your
      "PalmDev" installation.
    - "Readme.txt" will be installed to the root of your "PalmDev"
      installation.


Unix

To install the RPM:

	[log on as root]
	# rpm -ivh palmos-sdk-4.0-1.noarch.rpm

The RPM will install into "/opt/palmdev/sdk-4" by default, because
"/opt/palmdev" is the primary PalmDev location for prc-tools 2.1 and later.
If you want to install it elsewhere, for example if you are using prc-tools
2.0 which only searches "/usr/local/palmdev", you can add "--prefix" to the
installation command:

	# rpm -ivh --prefix /usr/local/palmdev palmos-sdk-4.0-1.noarch.rpm

Just as with any other RPM, if you're curious what has been installed:

	$ rpm -qil palmos-sdk

If you use Debian packages, you can install this via alien.  If you use
neither Debian nor RPM packages, you should install this SDK manually
from the sdk40-core.tar.gz archive.


Palm, Inc.
5470 Great America Parkway
Santa Clara, California 95052
(408) 326-9000

- Updated April 17, 2001 -
